home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 090 / mnpb.arc / MNPB.DOC next >
Text File  |  1987-03-02  |  23KB  |  639 lines
  1. @x1CB
  2.  
  3.  
  4.  
  5.  
  6.  
  7.      
  8.      
  9.      
  10.      
  11.      
  12.                          The Microcom MNP Library
  13.                       (Microsoft QuickBASIC Version)
  14.      
  15.      
  16.      
  17.                            PROGRAMMER'S MANUAL
  18.      
  19.      
  20.      
  21.      
  22.      
  23.      
  24.      
  25.      
  26.      
  27.      
  28.      
  29.      
  30.      
  31.      
  32.                                 Version 1.0
  33.      
  34.                              December 15, 1987
  35.      
  36.      
  37.      
  38.      
  39.      
  40.      
  41.      
  42.      
  43.      
  44.      
  45.      
  46.      
  47.      
  48.      
  49.      
  50.      
  51.      
  52.      
  53.      
  54.      
  55.      
  56.      
  57.      
  58.                               Microcom, Inc.
  59.                           1400 Providence Highway
  60.                             Norwood, MA 02062
  61.  
  62.  
  63.  
  64.  
  65.  
  66.      
  67.      
  68.      The Microcom MNP Library and MNP are trademarks of Microcom, Inc.
  69.      Microsoft and MS-DOS are trademarks of Microsoft Corporation.  IBM is a
  70.      registered trademark of International Business Machines.
  71.      
  72.      
  73.      This manual is not subject to copyright and may be freely copied.
  74.      
  75.      
  76.      
  77.      
  78.      
  79.      
  80.      
  81.      
  82.      
  83.      
  84.      
  85.      
  86.      
  87.      
  88.      
  89.      
  90.      
  91.      
  92.      
  93.      
  94.      
  95.      
  96.      
  97.      
  98.      
  99.      
  100.      
  101.      
  102.      
  103.      
  104.      
  105.      
  106.      
  107.      
  108.      
  109.      
  110.      Questions relating to the Microcom MNP Library should be directed to
  111.      Microcom at:
  112.      
  113.                               Microcom, Inc.
  114.                        15303 Ventura Blvd., Suite 900
  115.                           Sherman Oaks, CA 91403
  116.                                (818)986-4212
  117.  
  118.  
  119.  
  120.  
  121.  
  122.      
  123.      1. INTRODUCTION
  124.      
  125.           The Microcom MNP Library is a set of subroutines which implement the
  126.      stream mode of the link protocol in Microcom Networking Protocol (MNP).
  127.      This mode of the MNP link protocol is appropriate for interworking with MNP
  128.      error-correcting modems or with other software implementations which use
  129.      the Microcom MNP Library or other compatible software.
  130.      
  131.           This version of the library provides a set of assembly language
  132.      routines which are designed to be easily integrated into an application
  133.      program written in BASIC and compiled using the Microsoft QuickBASIC
  134.      compiler (version 1.02 or 2.0).  Through the use of these routines, an
  135.      application is able to perform error-free data communications over a
  136.      physical-connection, such as one established on the public switched
  137.      telephone network.
  138.      
  139.           These MNP Library subroutines are especially for the IBM Personal
  140.      Computer family (and compatibles) under PCDOS (MS-DOS).  Hardware
  141.      facilities for asynchronous communications are required.
  142.  
  143.  
  144.  
  145.  
  146.  
  147.      2. LIBRARY MODULES
  148.      
  149.           The Microcom MNP LIbrary is supplied in one of two forms, object
  150.      library only and object library with source.  The source version is de-
  151.      scribed in more detail in a manual addendum supplied as part of the source
  152.      version distribution.
  153.      
  154.           In the case of the object library only form, the distribution diskette
  155.      contains one file, mnpb.lib, which includes the various object modules
  156.      which make up the MNP Library.
  157.      
  158.           When building the executable form of a particular application, the
  159.      mnpb.lib file should be specified if the application calls any MNP sub-
  160.      routine described in this document.  The manner in which library modules
  161.      are specified for inclusion varies according to the linkage editor employed
  162.      in building the application program run module.
  163.  
  164.  
  165.  
  166.  
  167.  
  168.      3. LINK MANAGEMENT
  169.      
  170.           In general, the MNP link follows the life of the normal physical-
  171.      connection.  Immediately after the physical-connection is made (e.g. after
  172.      a modem first reports carrier detected), the application must attempt the
  173.      establishment of the Link via the MNPCONNECT subroutine.  MNP-capable
  174.      modems which answer the incoming telephone call, for example, must receive
  175.      the Link establishment sequence within 4 seconds of physical-connection
  176.      establishment.  If a link is not attempted within this period, such modems
  177.      may fall back to a normal connection and it will not be possible to provide
  178.      a reliable connection on that particular call.
  179.      
  180.           Link termination, performed via the MNPDISCONNECT call, should
  181.      immediately precede termination of the physical-connection, i.e. right
  182.      before hanging up the telephone.  Note that the Link is active for the
  183.      entire duration of the physical-connection.
  184.      
  185.           During the data phase of the Link (i.e. after establishment but before
  186.      termination), the Link must be kept running by allowing the Link code to
  187.      execute periodically.  Any of the data phase calls, namely MNPSEND,
  188.      MNPRECEIVE, MNPSTATUS, and MNPBREAK, will accomplish this.  One of these
  189.      routines must be called every 250ms or so which means that the Link code
  190.      gets a chance to run about 4 times per second.  The absolute interval is
  191.      not critical and it may be possible to reduce the frequency as well and
  192.      still get reasonable performance.  Polling the Link code, however, must
  193.      occur with a predictable frequency otherwise the Link may be lost.  When
  194.      the Link is lost, an MNP error-correcting modem may clear the call.
  195.      
  196.           When a Link is in progress, all line I/O is performed via the
  197.      appropriate MNP call rather than by using the BASIC COM file mechanism.
  198.      The BASIC COM file, however, must remain open.
  199.      
  200.           Data sent and received on the Link will be "chunked" depending on the
  201.      number of bytes which happen to be sent in a single data message.  The
  202.      maximum amount in a single message is 64 bytes.  This "chunking" is not
  203.      noticeable to the sender but can be perceived by the data receiver.
  204.      Strings of data may be split over more than one data message and some
  205.      messages may have to be sent more than once when there is noise on the
  206.      connection.  Retransmission can be seen by the application as an
  207.      interruption, possibly in the middle of some data string.  The application
  208.      should be examined to see if there are any cases involving timing
  209.      dependencies which could be adversely effected by this kind of irregularity
  210.      in the data flow.
  211.  
  212.  
  213.  
  214.  
  215.  
  216.      4. LINK INTERFACE SUBROUTINES
  217.      
  218.      4.1  Link Establishment - MNPCONNECT
  219.      
  220.           MNPCONNECT is used to establish a Link.  It is called after the
  221.      physical-connection has been established.  It can take up to 5 seconds for
  222.      an MNPCONNECT call to complete.
  223.      
  224.           MNPCONNECT has the following parameters:
  225.      
  226.                RATE - an integer which indicates the speed of the
  227.                       physical-connection, as follows:
  228.      
  229.                           1 = 110 bps
  230.                           2 = 300 bps
  231.                           3 = 1200 bps
  232.                           5 = 2400 bps
  233.      
  234.                       [Note: Other speeds are not supported in this
  235.                        version of the Microcom MNP Library.]
  236.      
  237.                FORMAT - an integer which indicates the data format,
  238.                         as follows:
  239.      
  240.                          0 = 8 data bits, no parity
  241.                          1 = 7 data bits, even parity
  242.                          2 = 7 data bits, odd parity
  243.                          3 = 7 data bits, mark parity
  244.                          4 = 7 data bits, space parity
  245.      
  246.                       [Note: In this Library version, once the Link
  247.                        is established, it is not possible to change
  248.                        format.]
  249.      
  250.                PORT -  an integer which indicates the communications
  251.                        port, as follows:
  252.      
  253.                          1 = COM1
  254.                          2 = COM2
  255.      
  256.                       [Note: This Library version does not support
  257.                        other comm ports.  Also, COM2 cannot be speci-
  258.                        fied if no COM1 is present in the system.]
  259.      
  260.                MODE - an integer which indicates the role in link
  261.                       establishment, as follows:
  262.      
  263.                          0 = link initiator (caller)
  264.                          1 = link accepter (answerer)
  265.      
  266.  
  267.  
  268.  
  269.  
  270.  
  271.                RETCODE - an integer returned to the caller which
  272.                          indicates the result of the link
  273.                          establishment attempt, as follows:
  274.      
  275.                          0 = success (link established)
  276.      
  277.                          -64 - failure, no additional info
  278.                          -65 - failure, timeout (no remote response)
  279.                          -66 - failure, physical-connection lost
  280.                                (carrier lost)
  281.                          -70 - failure, incompatible MNP
  282.                          -72 - failure, remote protocol error
  283.      
  284.                       [Note: -70 and -72 should never occur.]
  285.      
  286.      
  287.           MNPCONNECT is called as follows:
  288.      
  289.               CALL MNPCONNECT(RATE,FORMAT,PORT,MODE,RETCODE)
  290.  
  291.  
  292.  
  293.  
  294.  
  295.      4.2  Link Termination - MNPDISCONNECT
  296.      
  297.           MNPDISCONNECT has two functions, to send the appropriate protocol
  298.      message to the other side to indicate Link termination and to reset the PC
  299.      interrupt environment.  MNPDISCONNECT must always be called if MNPCONNECT
  300.      had been called previously.  This is so even for establishment failure or
  301.      for loss of the physical-connection (i.e. carrier lost).
  302.      
  303.           MNPDISCONNECT has no parameters.  It is called as follows:
  304.      
  305.                             CALL MNPDISCONNECT
  306.  
  307.  
  308.  
  309.  
  310.  
  311.      4.3  Send Data - MNPSEND
  312.      
  313.           MNPSEND is called to copy data to be sent on the Link from the
  314.      application into the MNP transmit buffer.
  315.      
  316.           MNPSEND has parameters as follows:
  317.      
  318.                SNDBUF$ - the BASIC string from which transmit data
  319.                          is to be copied.
  320.      
  321.                BUFLEN - an integer which indicates the maximum
  322.                         number of data bytes which can be copied
  323.                         from SNDBUF$.
  324.      
  325.                RETCODE - an integer returned to the caller which
  326.                          indicates the number of bytes copied from
  327.                          SNDBUF$ or a Link error condition, as follows:
  328.      
  329.                          positive int = number of bytes copied from
  330.                                         SNDBUF$.  0=no bytes copied
  331.      
  332.                          -64 = link terminated, retransmission limit
  333.                                exceeded
  334.                          -65 = link terminated, unable to send
  335.                          -66 = link terminated, carrier lost
  336.                          -67 = link terminated, remote disconnected
  337.      
  338.           MNPSEND is called as follows:
  339.      
  340.                   CALL MNPSEND(SNDBUF$,BUFLEN,RETCODE)
  341.  
  342.  
  343.  
  344.  
  345.  
  346.      4.4  Receive Data - MNPRECEIVE
  347.      
  348.           MNPRECEIVE is called to copy data received on the Link into the
  349.      application.  MNPRECEIVE transfers all available data up to the size of the
  350.      application buffer.  MNPRECEIVE returns immediately if no data is
  351.      available.
  352.      
  353.           MNPRECEIVE has the following parameters:
  354.      
  355.                RCVBUF$ - the BASIC string into which received
  356.                          data is to be copied.  This string must
  357.                          be created by the application to be as
  358.                          long as the value of BUFLEN.
  359.      
  360.                BUFLEN - an integer which indicates the maximum
  361.                         number of data bytes which can be copied
  362.                         into RCVBUF$
  363.      
  364.                RETCODE - an integer returned to the caller which
  365.                          indicates the number of bytes copied into
  366.                          RCVBUF$ or a Link error condition, as follows:
  367.      
  368.                          positive int = number of bytes copied into
  369.                                         RCVBUF. 0=no bytes available.
  370.      
  371.                          -64 = link terminated.  retransmission limit
  372.                                exceeded
  373.                          -65 = link terminated, unable to send
  374.                          -66 = link terminated,  carrier lost
  375.                          -67 = link terminated, remote disconnected
  376.      
  377.           MNPRECEIVE is called as follows:
  378.      
  379.                   CALL MNPRECEIVE(RCVBUF$,BUFLEN,RETCODE)
  380.  
  381.  
  382.  
  383.  
  384.  
  385.      4.5  Link Status - MNPSTATUS
  386.      
  387.           MNPSTATUS is called to return to the application the status of the
  388.      Link and to read parameters which indicate the availability of received
  389.      data or the ability to enqueue data for transmission.
  390.      
  391.           MNPSTATUS has parameters as follows:
  392.      
  393.                PSTATUS - an integer which indicates the condition of
  394.                          the physical-connection, as follows:
  395.      
  396.                          0 = not connected (carrier not present)
  397.                          1 = connected (carrier present)
  398.      
  399.                LSTATUS - an integer which indicates the condition of
  400.                          Link, as follows:
  401.      
  402.                          0 = link not established (i.e. link
  403.                              terminated)
  404.                          1 = link established
  405.      
  406.                SCOUNT - an integer which indicates the number of
  407.                         bytes free in the Link send buffer.  This is
  408.                         the number of bytes which can be completely
  409.                         copied to the Link transmit code via an
  410.                         MNPSEND call.
  411.      
  412.                RCOUNT - an integer which indicates the number of
  413.                         received data bytes which are available to
  414.                         be copied into the application via MNPRECEIVE
  415.      
  416.                ALLSENT - an integer which indicates whether or not
  417.                          all data passed to the Link code has been
  418.                          successfully sent and acknowledged, as
  419.                          follows:
  420.      
  421.                          0 = all data not sent
  422.                          1 = all data sent
  423.      
  424.      
  425.           MNPSTATUS is called as follows:
  426.      
  427.            CALL MNPSTATUS(PSTATUS,LSTATUS,SCOUNT,RCOUNT,ALLSENT)
  428.  
  429.  
  430.  
  431.  
  432.  
  433.      4.6  Send Signal - MNPBREAK
  434.      
  435.           MNPBREAK is called to send a signal to the remote DTE.  When the
  436.      remote side is an MNP error-correcting modem, an MNPBREAK call causes the
  437.      remote modem to send a break signal (continuous spacing) to its attached
  438.      DTE.
  439.      
  440.           MNPBREAK employs the MNP Link Protocol's reliable attention
  441.      mechanism in 'destructive mode'.  That is, when MNPBREAK is called, the
  442.      Link is reset and any data pending transmission on the link is discarded as
  443.      is any received data which has not been read via the MNPRECEIVE subroutine.
  444.      Data may also be discarded at the remote side of the Link.
  445.      
  446.           MNPBREAK has one parameter as follows:
  447.      
  448.                RETCODE - an integer returned to the caller which
  449.                          indicates the result of the MNPBREAK call
  450.                          or a Link error condition, as follows:
  451.      
  452.                          0 = break initiated
  453.      
  454.                          -64 = link terminated, retransmission limit
  455.                                exceeded
  456.                          -65 = link terminated, unable to send
  457.                          -66 = link terminated, carrier lost
  458.                          -67 = link terminated, remote disconnected
  459.                          -75 = break not supported (remote did not
  460.                                negotiate attention support for this
  461.                                Link)
  462.                          -76 = previous break still in progress
  463.      
  464.      
  465.           MNPBREAK is called as follows:
  466.      
  467.                           CALL MNPBREAK(RETCODE)
  468.      
  469.      
  470.      
  471.           [Note that the MNP Library does not support receipt of the MNP
  472.      attention message and hence it is assumed that MNPBREAK will only be
  473.      employed when the remote side of the connection is an MNP error-correcting
  474.      modem.]
  475.  
  476.  
  477.  
  478.  
  479.  
  480.      5. SAMPLE PROGRAM
  481.      
  482.           A demonstration program is provided on the distribution diskette in
  483.      the file testb.exe.  A listing of this program follows in the next pages.
  484.      
  485.      '==========================================================================
  486.      '
  487.      '       MNP INTERFACE TEST PROGRAM
  488.      '
  489.      '       This test program is a simple terminal emulator which
  490.      '       exercises the assembly language routines which interface
  491.      '       QuickBASIC to the MNP library.
  492.      '
  493.      '             - G. Pearson, September 1986
  494.      '
  495.      '==========================================================================
  496.      
  497.      '----- Data declarations
  498.      defint a-z
  499.      
  500.      '----- Initialize
  501.      rbuflen=80                              ' make receive buffer be a
  502.      rcvbuf$=string$(rbuflen,32)             '   a blank string of right
  503.                                              '   length
  504.      
  505.      '----- Display herald screen
  506.      cls                                     ' clear screen
  507.      print "-------------------------------------------------------------------"
  508.      print
  509.      print "                     MNP Link Demonstration Program"
  510.      print
  511.      print "        This simple terminal emulation program demonstrates the use"
  512.      print "        of the Microcom MNP Library to provide error-free data"
  513.      print "        com munications."
  514.      print
  515.      print
  516.      print "        Hit any key to begin..."
  517.      print
  518.      print "-------------------------------------------------------------------"
  519.      
  520.      startloop:
  521.          if inkey$="" then goto startloop
  522.      print
  523.      
  524.      '----- Get user parameter selections
  525.      ' Comm port number...
  526.      parms:
  527.          input "Enter comm port number (1/2)";port$
  528.          if (port$="1" or port$="2") then goto parms1 _
  529.          else goto parms
  530.      
  531.  
  532.  
  533.  
  534.  
  535.  
  536.      ' Port speed...
  537.      parms1:
  538.          input "Enter port speed (300/1200/2400)";spd$
  539.          if (spd$="300" or spd$="1200" or spd$="2400") then goto parms2 _
  540.          else goto parms1
  541.      
  542.      ' Telephone number...
  543.      parms2:
  544.          input "Enter telephone number of MNP remote";number$
  545.          if number$="" then goto parms2
  546.      
  547.      '----- Open comm file
  548.      opncom:
  549.          open "com"+port$+":"+spd$+",n,8,1,cs,ds,cd" as #1
  550.      
  551.      '----- Initialize modem (Hayes 2400-compatible assumed)
  552.      a$=""
  553.      print #1,"ATE0Q0V0"                     ' no cmd echo,result codes,
  554.                               '   numeric codes
  555.      for i=1 to 1000:next i                  ' let cmds get out...
  556.      close #1                 ' trash modem response
  557.      open "com"+port$+":"+spd$+",n,8,1,cs,ds,cd" as #1     ' re-open modem
  558.      
  559.      '----- Dial MNP-capable remote and wait for connect
  560.      print                                   ' inform user
  561.      print "dialing "+number$+"..."
  562.      print #1,"ATDT"+number$                 ' send dial string to modem
  563.      print "-- waiting for physical-connection establishment..."
  564.      connwait:                               ' wait for modem or user abort
  565.          if (inkey$<>"") then goto xitpgm    ' any user input will abort...
  566.          if loc(1)=0 then goto connwait
  567.          a$=input$(1,#1)                     ' get modem response code
  568.          if (a$<>"1") then goto connwait     ' wait till connect or user abort
  569.          print "physical-connection established."
  570.      
  571.      '----- Initiate Link
  572.      startlink:
  573.          for i=1 to 10000:next i             ' let line settle...
  574.          print "-- starting link..."         ' pass line speed
  575.          rate=5                              ' assume 2400 bps
  576.          if (spd$="1200") then rate=4        ' adjust for other speeds...
  577.          if (spd$="300") then rate=2
  578.          format=1                            ' assume 7 bits, even parity
  579.          if (port$="1") then port=1 else port=2 ' pass comm port number
  580.          mode=0                              ' caller is link initiator
  581.          call mnpconnect(rate,format,port,mode,retcode) ' try for link
  582.          if retcode<>0 then goto xitpgm     ' just quit if failure
  583.      
  584.      '----- Link established. Notify user and wait to continue.
  585.      print
  586.      print "***** Link established.  Hit any key to continue... *****"
  587.  
  588.  
  589.  
  590.  
  591.  
  592.      '----- Now wait for user input before starting terminal emulation.
  593.      ' Note that the application must poll the link code while waiting
  594.      ' in order to keep the link alive.
  595.      startwait:
  596.          call mnpstatus(pstatus,lstatus,scount,rcount,allsent)
  597.          if pstatus=0 then print "carrier lost":goto xitpgm
  598.          if lstatus=0 then print "link lost":goto xitpgm
  599.          if inkey$="" then goto startwait
  600.      
  601.      '----- Start terminal emulation with a clear screen and tell the
  602.      ' user how to terminate the program.
  603.      cls
  604.      print "Begin terminal emulation.  A slash (/) will exit program."
  605.           
  606.      '----- Data phase of Link
  607.      mainloop:
  608.          retcode=0
  609.          call mnpstatus(pstatus,lstatus,scount,rcount,allsent)
  610.          if (pstatus=0) then print "carrier lost":goto xitpgm
  611.          b$=inkey$
  612.          if (b$="") then goto getcomm
  613.          if (b$="/") then goto xitpgm
  614.      
  615.      sndagain:
  616.          call mnpsend(b$,len(b$),retcode)
  617.          if (retcode<0) then _
  618.           print "link failed on send": _
  619.           goto xitpgm
  620.          if (retcode<>len(b$)) then goto sndagain
  621.          retcode=0
  622.      
  623.      getcomm:
  624.          if (rcount>0) then call mnpreceive(rcvbuf$,rbuflen,retcode)
  625.          if (retcode<0) then _
  626.           print "link failed on receive": _
  627.           goto xitpgm
  628.          if (retcode>0) then print using "&";left$(rcvbuf$,retcode);
  629.          goto mainloop
  630.      
  631.      '----- Exit
  632.      xitpgm:
  633.          print
  634.          print "-- disconnecting link..."
  635.          call mnpdisconnect
  636.          print
  637.          print "end of test program"
  638.          close
  639.          system